Banners API endpoints

Banner (creative) management, uploads, and linking. 61 endpoints, generated from the OpenAPI spec. Authentication, the response envelope, pagination and error codes are shared by all endpoints — see REST API overview. Parameters marked form go in an application/x-www-form-urlencoded request body.

GET /rest-api/banner/{bannerId}.do

Request examples

Get banner by ID.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to retrieve
selfServRequest	query	boolean	no	If true, returns the Self-Serve response format

Responses: 200 — Banner details · 404 — Banner not found. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/{operation}/{campaignId}.do

Request examples

Copy or move banner to campaign.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to copy or move
operation	path	string	yes	Operation to perform: COPY or MOVE Values: MOVE, COPY.
campaignId	path	integer	yes	ID of the target campaign to copy/move the banner to
copyCount	form	integer	no	Number of copies to create, 1 to 20 (only for COPY operation, default: 1)
keepBannersLinked	form	boolean	no	If true, the copied or moved banner stays linked to the source banner’s placements (those the user can access); if false it ends up with no placement links
name	form	string	no	Name for the copy (COPY only, at most 500 characters). With copyCount above 1 the later copies are named ‘<name> 2’, ‘<name> 3’… Omit to keep the source’s name (with ‘_copy’ appended when the target campaign already has one of that name).

Responses: 200 — Banner copied or moved successfully · 404 — Not found — resource does not exist · 500 — Internal server error. When a COPY fails after saving some copies, the message says which copy failed and created lists the saved copies. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/{operation}/bulk.do

Request examples

Bulk copy or move banner to multiple campaigns.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to copy or move
operation	path	string	yes	Operation to perform: COPY or MOVE Values: MOVE, COPY.
campaignIds	form	array<integer>	no	IDs of the target campaigns to copy/move the banner to
copyCount	form	integer	no	Number of copies to create per campaign, 1 to 20 (only for COPY, default: 1)
keepBannersLinked	form	boolean	no	If true, the copied or moved banner stays linked to the source banner’s placements (those the user can access); if false it ends up with no placement links

Responses: 200 — Bulk operation completed · 404 — Not found — resource does not exist. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/approvalstatus.do

Request examples

Change banner approval status.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to change approval status for
status	form	string	yes	New approval status: NEW, PENDING, APPROVED, or REJECTED Values: NEW, PENDING, APPROVED, REJECTED.

Responses: 200 — Approval status changed · 404 — Not found — resource does not exist. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/bannerPricing/actionPricing.do

Request examples

Update banner CPA action pricing.

Parameter	In	Type	Required	Description
price	form	number	yes	Action price value, 0 to 1000000
bannerId	path	integer	yes	ID of the banner
actionName	form	string	no	Name of the action to price
actionKey	form	string	no	Key of the action to price (takes precedence over actionName)

Responses: 200 — Action pricing updated · 404 — No action the caller can see matches actionKey/actionName. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/capping/frequency.do

Request examples

Set banner frequency capping.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to set frequency capping for
amount	form	integer	no	Maximum number of impressions/clicks allowed within the capping period
flat	form	boolean	no	Whether to use flat (non-rolling) period windows
id	form	integer	no	Frequency capping rule ID
period	form	integer	no	Length of the capping period (combined with periodType)
periodType	form	string	no	Period type for the capping window (MINUTE, HOUR, DAY, WEEK, MONTH, YEAR) Values: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR.
subject	form	string	no	Subject type for capping identification (USER_COOKIE, USER_SERVER_SIDE, USER_MIXED, IP, LES_IP) Values: USER_COOKIE, USER_SERVER_SIDE, USER_MIXED, IP, LES_IP.

Responses: 200 — Frequency capping updated · 404 — Not found — resource does not exist. Errors follow the shared conventions.

DELETE /rest-api/banner/{bannerId}/capping/frequency.do

Request examples

Delete banner frequency capping.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to remove frequency capping from

Responses: 200 — Frequency capping removed · 404 — Not found — resource does not exist. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/custom/parameters.do

Request examples

Update banner custom parameters.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to update custom parameters for

Request body (application/json, required): JSON array; each element a JSON object with fields id, name, value.

Responses: 200 — Custom parameters updated successfully · 404 — Not found — resource does not exist. Errors follow the shared conventions.

DELETE /rest-api/banner/{bannerId}/delete.do

Request examples

Delete banner.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to delete

Responses: 200 — Banner deleted · 404 — Not found — resource does not exist. Errors follow the shared conventions.

GET /rest-api/banner/{bannerId}/matchplacements.do

Request examples

Get matching placements for banner.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to find matching placements for
publisherCategories	query	array<integer>	no	IDs of publisher categories to filter matching placements by
labels	query	array<string>	no	Label names to filter matching placements by

Responses: 200 — List of matching placements · 404 — Banner not found. Errors follow the shared conventions.

GET /rest-api/banner/{bannerId}/mismatched-placements.do

Request examples

List placements of a banner’s size it cannot be linked to.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner

Responses: 200 — List of placements of the banner’s size it cannot be linked to · 404 — Banner not found or deleted. Errors follow the shared conventions.

GET /rest-api/banner/{bannerId}/placements.do

Request examples

Get banner placements.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to list linked placements for

Responses: 200 — List of linked placements · 404 — Banner not found. Errors follow the shared conventions.

GET /rest-api/banner/{bannerId}/pricing.do

Request examples

Get banner pricing.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to retrieve pricing for

Responses: 200 — Banner pricing details · 404 — Banner pricing not found. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/pricing.do

Request examples

Update banner pricing.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to update pricing for
paymentModel	form	string	no	Payment model (FIXED_PRICE, REVENUE_SHARE) Values: FIXED_PRICE, REVENUE_SHARE.
price	form	number	no	Price value in the selected pricing type; null when no global price is set
pricingType	form	string	no	Pricing type (CPM, CPC, CPA, COST_PER_DAY, COST_PER_MONTH) Values: CPM, CPC, CPA, COST_PER_DAY, COST_PER_MONTH.
useGlobalActionPricing	form	boolean	no	Whether to use global action pricing from the action definition

Responses: 200 — Banner pricing updated · 404 — Banner not found. Errors follow the shared conventions.

DELETE /rest-api/banner/{bannerId}/pricing.do

Request examples

Delete banner pricing.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to remove pricing from

Responses: 200 — Banner pricing removed · 404 — Not found — resource does not exist. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/pricing/{countryCode}.do

Request examples

Set banner country pricing.

Parameter	In	Type	Required	Description
price	form	number	yes	Price for the country, 0 to 1000000
bannerId	path	integer	yes	ID of the banner to set country pricing for
countryCode	path	string	yes	ISO 3166 two-letter country code (e.g., US, GB)
actionId	form	integer	no	CPA banners only: the conversion action this country price is for; omit to price every action

Responses: 200 — Country pricing updated · 404 — Banner not found, or actionId names no action the caller can see. Errors follow the shared conventions.

DELETE /rest-api/banner/{bannerId}/pricing/{countryCode}.do

Request examples

Delete banner country pricing.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to remove country pricing from
countryCode	path	string	yes	ISO 3166 two-letter country code to remove pricing for

Responses: 200 — Country pricing removed · 404 — Banner not found, or it has no price for the country. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/pricing/batch.do

Request examples

Batch update banner country pricing from CSV.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to batch-update country pricing for
countryPricesCsv	form	string	no	The CSV’s text, for a client that cannot upload a file; send this or countryPrices

Request body (multipart/form-data): form with field countryPrices — CSV file with the country prices; send this or countryPricesCsv.

Responses: 200 — Batch update result: applied and rejected lines, plus the legacy csvErrors and csvWarnings · 404 — Banner not found. Errors follow the shared conventions.

GET /rest-api/banner/{bannerId}/template-properties.do

Request examples

Get a template banner’s property values.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the TEMPLATE banner

Responses: 200 — The template and its properties with the banner’s values · 404 — Banner not found or deleted. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/template-properties.do

Request examples

Set a template banner’s property values.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the TEMPLATE banner

Request body (application/json): JSON object.

Responses: 200 — Saved; the template and its properties with the banner’s new values · 404 — Banner not found or deleted. Errors follow the shared conventions.

POST /rest-api/banner/{bannerId}/update.do

Request examples

Update banner.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner to update
autolinkCategories	form	array<integer>	no	IDs of the publisher categories whose new placements the banner auto-links to, comma-separated or repeated — optional: with none set, autoLinkLabels alone decide; with both set, a placement must match both
autoLinkLabels	form	array<string>	no	Label names whose new placements the banner auto-links to (the placement needs at least one of them), comma-separated or repeated — a name that does not exist yet is created. Works with or without autolinkCategories
active	form	boolean	no	Whether the banner is active
adUnitHeight	form	integer	no	Ad unit height in pixels: the size of a custom ad unit, or without adUnitId the size to pick the ad unit by
adUnitId	form	integer	no	Ad unit ID for the banner dimensions; list them with GET /rest-api/ad-units.do. When omitted, adUnitWidth and adUnitHeight pick the ad unit of that size for the placement type, or its custom ad unit. On update, omitting all three keeps the stored size
adUnitWidth	form	integer	no	Ad unit width in pixels: the size of a custom ad unit, or without adUnitId the size to pick the ad unit by
additionalParameters	form	object	no	Additional banner parameters as key-value pairs, e.g. additionalParameters[‘flashVars’]. On update the keys sent are set and the others kept; a key sent with an empty value is removed. The click target is the separate target field
advertisingNetworkParameters	form	object	no	Advertising network parameters for DSP banners. Valid keys: NATIVE_ADAPTER_TEMPLATE_ID, TEMPLATE_ID, BROKER_URL, WIN_NOTIFICATION_URL, DSP_TRAFFIC_TIER, BANNER_MASK_INVENTORY, SECOND_PRICE_ONLY, ALLOW_EMPTY_DSP_UID, DSP_CUSTOM_CURRENCY, USD_TO_DSP_CUSTOM_CURRENCY_RATE, CONTENT_ADAPTER_TEMPLATE_ID, FORCE_FIRST_PRICE, LURL_NOTIFICATION, LURL_NOTIFICATION_AUCTION_PRICE_AVAILABLE, HASH_PUBLISHER_SITE_FIELDS_VALUES, ADD_SOURCE_SCHAIN, CUSTOM_SOURCE_SCHAIN_ASI, INTERSTITIAL
allowNewPlacementsAutoLinking	form	boolean	no	Allow auto-linking to new placements
allowUseForTemplate	form	boolean	no	Allow use of this banner as a template
always2ndPrice	form	boolean	no	Always use second-price auction for this banner
applicationAdCategory	form	string	no	Application ad category. Allowed values: BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO Values: BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO.
applicationOperatingSystem	form	string	no	Target operating system for application banners. Allowed values: ANDROID, IOS Values: IOS, ANDROID.
applicationPreCheckPackages	form	string	no	App banner: packages to check on the device before showing the banner, comma-separated. Needs the Application Pre-Check permission
bannerType	form	string	conditional	Conditionally required — when creating a banner that is not built from a self-serve prototype (selfServeCampaignType). Creative type, which decides the fields that carry the creative: EXTERNAL_FILE - image hot-linked from imageBannerLink, click URL in url, size from adUnitId (or adUnitWidth + adUnitHeight); CODE - HTML/JS in code; VAST_2_0_TAG_URL - third-party VAST/VPAID tag in vastTagUrl (placementType VIDEO_PLACEMENT, size optional); EXTERNAL_VIDEO - video file URL in videoFileLink, click URL in url; TEMPLATE - templateId plus one request parameter per template property, named by the property key (see GET /rest-api/template/{id}/properties.do), an HTML5 ZIP property filled by html5ZipUrl and a FILE property by fileUrl; EXTERNAL_NATIVE - iconUrl / imageUrl / videoUrl (hot-linked) with title, description, callToAction and clickUrl; OPENRTB_DSP - dspPartnerId; LOCAL_FILE - the image stored on the ad server, uploaded as imageFile or fetched from imageFileUrl, click URL in url, size from adUnitId; LOCAL_VIDEO - the video stored on the ad server, uploaded as videoFile or fetched from videoFileUrl; LOCAL_NATIVE - icon / image / video stored on the ad server, uploaded as nativeIconFile / nativeImageFile / nativeVideoFile or fetched from nativeIconFileUrl / nativeImageFileUrl / nativeVideoFileUrl, with title, description, callToAction and clickUrl. Values: LOCAL_VIDEO, EXTERNAL_VIDEO, VAST_2_0_TAG_URL, VPAID_FRAMEWORK, ADVANCED_LOCAL_VIDEOS, LOCAL_FILE, EXTERNAL_FILE, CODE, TEMPLATE, OPENRTB_DSP, LOCAL_NATIVE, EXTERNAL_NATIVE.
boundedInstallActionId	form	integer	no	Mobile / app banner: id of the conversion action tracking the app install
callToAction	form	string	no	Call-to-action text for native banners
clickUrl	form	string	no	Click URL for native banners
code	form	string	no	HTML/JavaScript markup of a CODE banner
customParameters	form	array<object>	no	Custom native banner parameters
description	form	string	no	Description text for native banners
directFileDownload	form	boolean	no	Whether to enable direct file download for the banner
displayType	form	string	no	Android interstitial app banner: show it as a VIEW or as an ACTIVITY Values: VIEW, ACTIVITY.
dspPartnerId	form	integer	no	DSP partner ID for OpenRTB banners
enablePassbackFunctionality	form	boolean	no	Enable passback functionality for this banner
enableViewTracking	form	boolean	no	Whether to enable view tracking for this banner. Needs the Banner View Tracking permission
hardLinkage	form	boolean	no	Hard linkage: when true the banner serves only on the placements it is linked to. Needs the Link Placements to Banners permission
hostExternalFiles	form	boolean	no	EXTERNAL_FILE, EXTERNAL_VIDEO and EXTERNAL_NATIVE only: download the files from imageBannerLink / videoFileLink / iconUrl, imageUrl, videoUrl and serve our stored copy instead of the links. The links are kept; a changed link is downloaded again; false serves the links again and drops the copy. Omitted keeps the current setting.
iconHeight	form	integer	no	Native icon height in pixels
iconUrl	form	string	no	External URL to native icon image; an empty value removes it, omitted keeps it
iconWidth	form	integer	no	Native icon width in pixels
imageBannerLink	form	string	no	Image URL of an EXTERNAL_FILE banner. The image is hot-linked from this address at serve time unless hostExternalFiles is on; it should match the ad unit’s size.
imageFileUrl	form	string	no	URL of the image of a LOCAL_FILE banner - the multipart-free way to upload imageFile: the image is downloaded and stored as the banner’s own file (served from the ad server/CDN, not hot-linked; for a hot-linked image use EXTERNAL_FILE with imageBannerLink). GIF, JPEG, PNG or SVG (sanitised); the console’s size limit for the ad unit applies. On update it replaces the stored image. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
imageHeight	form	integer	no	Native image height in pixels
imageUrl	form	string	no	External URL to native image; an empty value removes it, omitted keeps it
imageWidth	form	integer	no	Native image width in pixels
inStreamVideoType	form	string	no	In-stream video ad type. Allowed values: LINEAR_VIDEO_AD (linear video), NON_LINEAR_VIDEO_AD (overlay) Values: LINEAR_VIDEO_AD, NON_LINEAR_VIDEO_AD.
labelUpdateType	form	string	no	How to update labels. Allowed values: add (append), overwrite (replace all existing), remove (delete specified), clear (remove all) Values: ADD, OVERWRITE, REMOVE, CLEAR.
labels	form	array<string>	no	Labels to apply to the banner
mimeTypes	form	string	no	OPENRTB_DSP banner on a video placement: video MIME types sent in the bid request, comma-separated. Needs the Open RTB permission
name	form	string	no	Banner name, up to 512 characters and never blank
nativeIconFileUrl	form	string	no	URL of the icon of a LOCAL_NATIVE banner - the multipart-free way to upload nativeIconFile. GIF, JPEG, PNG or SVG; fitted to iconWidth x iconHeight as an upload is. On update it replaces the stored icon. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
nativeImageFileUrl	form	string	no	URL of the main image of a LOCAL_NATIVE banner - the multipart-free way to upload nativeImageFile. GIF, JPEG, PNG or SVG; fitted to imageWidth x imageHeight as an upload is. On update it replaces the stored image. If its file name is already taken by the icon it is stored as image-<name>. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
nativeVideoFileUrl	form	string	no	URL of the video of a LOCAL_NATIVE banner - the multipart-free way to upload nativeVideoFile. MP4, at least videoWidth x videoHeight in the same orientation, up to the video size limit. On update it replaces the stored video. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
rating	form	number	no	Rating value for native banners (e.g., app store rating)
returnAsIframe	form	boolean	no	Video-placement banner: return the creative inside an iframe in the VAST response
skipButtonShowAfterSeconds	form	integer	no	Video banner: seconds before the player shows the skip button. Needs the Video Skip Button permission
subtitle	form	string	no	Subtitle text for native banners
target	form	string	no	HTML link target for the banner’s click-through URL (not applicable to CODE type) Values: _BLANK, _PARENT, _SELF, _TOP.
targetTemplateName	form	string	no	Target template name for template-based banners, up to 50 characters
thirdTrackingCode	form	object	no	Third-party tracking code (HTML/JavaScript fired with the impression) per country: thirdTrackingCode[*] for every country, thirdTrackingCode[US] for one - the key is * or a two-letter country code (any case; stored upper-case, GB as UK); any other key is not applied and is listed in ignoredFields. An empty value removes that code. Not applied to EXTERNAL_VIDEO banners. Needs the BANNER_THIRD_PARTY_TRACKING permission.
title	form	string	no	Title text for native banners
universalAdIdRegistry	form	string	no	Registry of the video creative’s Universal Ad ID (VAST UniversalAdId idRegistry); empty with a code set means ad-id.org
universalAdIdValue	form	string	no	ISCI / Ad-ID code of the video creative, sent as the VAST UniversalAdId; an empty string clears it
url	form	string	no	Click-through (landing page) URL of EXTERNAL_FILE, LOCAL_FILE, EXTERNAL_VIDEO, LOCAL_VIDEO and TEMPLATE banners. For a VAST_2_0_TAG_URL banner this field stores the VAST tag URL; send it as vastTagUrl instead.
usePlacementSize	form	boolean	no	Use placement size instead of banner size
vast40WrapperAllowMultipleAds	form	boolean	no	VAST 4.0: allow multiple ads in response
vast40WrapperFallbackOnNoAds	form	boolean	no	VAST 4.0: fallback when no ads available
vast40WrapperFollowAdditionalWrappers	form	boolean	no	VAST 4.0: follow additional wrapper redirects
vastTagUrl	form	string	no	Third-party VAST/VPAID tag URL of a VAST_2_0_TAG_URL banner (placementType VIDEO_PLACEMENT). Takes precedence over url, which older clients send for the same value. The player follows the tag, so the banner needs no ad unit; adUnitWidth + adUnitHeight are kept when given.
videoFileLink	form	string	no	Video file URL of an EXTERNAL_VIDEO banner
videoFileName	form	string	no	Video file name
videoFileUrl	form	string	no	URL of the video of a LOCAL_VIDEO banner - the multipart-free way to upload videoFile: the video (MP4 or FLV) is downloaded and stored as the banner’s own file, up to the configured video size limit (20 MB by default, never more than 100 MB). On update it replaces the stored video. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
videoHeight	form	integer	no	Native video height in pixels
videoUrl	form	string	no	External URL to native video; an empty value removes it, omitted keeps it
videoWidth	form	integer	no	Native video width in pixels
weight	form	integer	no	Banner weight for rotation (higher weight = more impressions), 1 to 32767
templateId	form	integer	conditional	Conditionally required — when bannerType is TEMPLATE. Template ID
vpaidFrameworkId	form	integer	conditional	Conditionally required — when bannerType is VPAID_FRAMEWORK. VPAID framework ID
linkToPlacements	form	boolean	no	If true, after the update link the banner to every placement its auto-linking rules match: the banner’s own when allowNewPlacementsAutoLinking is on (narrowed by autolinkCategories / autoLinkLabels), otherwise its campaign’s. With auto-linking off on both, or without the Link Placements to Banners or Auto-Linking Settings permission, nothing is linked and the field is listed in ignoredFields with the reason.
selfServRequest	form	boolean	no	If true, applies Self-Serve template property handling
status	form	string	no	New approval status to set (NEW, PENDING, APPROVED, REJECTED). Changing it needs the BANNERS_APPROVAL permission; without it the status is left as it is and listed in ignoredFields, while the rest of the update is saved. Sending the current status changes nothing. Values: NEW, PENDING, APPROVED, REJECTED.
deleteImage	form	boolean	no	If true, removes the banner’s current image file; a LOCAL_FILE banner must then upload its replacement in imageFile. imageFileUrl replaces the image without it.
mediaAssetId	form	integer	no	Media library file the creative uses instead of an upload (GET /rest-api/media-library/assets.do): a video for LOCAL_VIDEO, an image for LOCAL_FILE, a video ADVANCED_LOCAL_VIDEOS adds to its media files. The file is referenced, not copied. A TEMPLATE banner whose template has one HTML5 ZIP property takes a library ZIP here; with several, send mediaAsset.<property key> per property, e.g. mediaAsset.$$HTML5_HEAD$$=42. Requires the MEDIA_LIBRARY permission.
html5ZipUrl	form	string	no	URL of the HTML5 creative’s ZIP archive, for a TEMPLATE banner whose template has one HTML5 ZIP property - the way to supply it without a multipart upload. At most 10 MB; the archive must unpack within the HTML5 limits (by default 1000 files, 20 MB a file, 50 MB in all, no path outside its folder). The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. For a template with several HTML5 ZIP properties send html5ZipUrl[<property key>] per property instead, e.g. html5ZipUrl[$$HTML5_HEAD$$]. On update it replaces the stored archive.
fileUrl	form	string	no	URL of the file for a TEMPLATE banner’s FILE property (an image or video the template renders) - the way to supply it without a multipart upload; the file must be of a content type the property allows. At most the video size limit (10 MB when that is lower). The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. For a template with several FILE properties send fileUrl[<property key>] per property instead, e.g. fileUrl[$$IMAGE$$]. On update it replaces the stored file.
refreshHostedFiles	form	boolean	no	With hostExternalFiles on: download every link of the EXTERNAL_FILE, EXTERNAL_VIDEO or EXTERNAL_NATIVE banner again, for a file that changed behind an unchanged link. A link that changed is downloaded again without it.

Request body (multipart/form-data): form with fields imageFile, nativeIconFile, nativeImageFile, nativeVideoFile, videoFile.

Responses: 200 — Banner updated successfully · 404 — Not found — resource does not exist. Errors follow the shared conventions.

GET /rest-api/banner/{bannerId}/video-compliance.do

Request examples

Get a video banner’s file facts and publisher compliance.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner

Responses: 200 — File facts and compliance per site · 404 — Banner not found. Errors follow the shared conventions.

DELETE /rest-api/banner/{bannerId}/video.do

Request examples

Delete banner video file.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	ID of the banner whose video file is removed

Responses: 200 — Video file deleted · 404 — Banner not found or deleted. Errors follow the shared conventions.

GET /rest-api/banner/adunit/values.do

Request examples

Get ad unit values by placement type.

Parameter	In	Type	Required	Description
placementType	query	string	yes	Placement type: SITE_PLACEMENT, MOBILE_SITE_PLACEMENT, VIDEO_PLACEMENT, or APPLICATION_PLACEMENT Values: SITE_PLACEMENT, NON_STANDARD_SITE_PLACEMENT, MOBILE_SITE_PLACEMENT, VIDEO_PLACEMENT, APPLICATION_PLACEMENT, EMAIL_PLACEMENT, CLICK_THROUGH_PLACEMENT, NATIVE_PLACEMENT.

Responses: 200 — List of ad unit values · 404 — No matching ad units found. Errors follow the shared conventions.

POST /rest-api/banner/create.do

Request examples

Create banner.

Parameter	In	Type	Required	Description
campaignId	form	integer	yes	ID of the campaign to create the banner under
autolinkCategories	form	array<integer>	no	IDs of the publisher categories whose new placements the banner auto-links to, comma-separated or repeated — optional: with none set, autoLinkLabels alone decide; with both set, a placement must match both
autoLinkLabels	form	array<string>	no	Label names whose new placements the banner auto-links to (the placement needs at least one of them), comma-separated or repeated — a name that does not exist yet is created. Works with or without autolinkCategories
active	form	boolean	no	Whether the banner is active
adUnitHeight	form	integer	no	Ad unit height in pixels: the size of a custom ad unit, or without adUnitId the size to pick the ad unit by
adUnitId	form	integer	no	Ad unit ID for the banner dimensions; list them with GET /rest-api/ad-units.do. When omitted, adUnitWidth and adUnitHeight pick the ad unit of that size for the placement type, or its custom ad unit. On update, omitting all three keeps the stored size
adUnitWidth	form	integer	no	Ad unit width in pixels: the size of a custom ad unit, or without adUnitId the size to pick the ad unit by
additionalParameters	form	object	no	Additional banner parameters as key-value pairs, e.g. additionalParameters[‘flashVars’]. On update the keys sent are set and the others kept; a key sent with an empty value is removed. The click target is the separate target field
advertisingNetworkParameters	form	object	no	Advertising network parameters for DSP banners. Valid keys: NATIVE_ADAPTER_TEMPLATE_ID, TEMPLATE_ID, BROKER_URL, WIN_NOTIFICATION_URL, DSP_TRAFFIC_TIER, BANNER_MASK_INVENTORY, SECOND_PRICE_ONLY, ALLOW_EMPTY_DSP_UID, DSP_CUSTOM_CURRENCY, USD_TO_DSP_CUSTOM_CURRENCY_RATE, CONTENT_ADAPTER_TEMPLATE_ID, FORCE_FIRST_PRICE, LURL_NOTIFICATION, LURL_NOTIFICATION_AUCTION_PRICE_AVAILABLE, HASH_PUBLISHER_SITE_FIELDS_VALUES, ADD_SOURCE_SCHAIN, CUSTOM_SOURCE_SCHAIN_ASI, INTERSTITIAL
allowNewPlacementsAutoLinking	form	boolean	no	Allow auto-linking to new placements
allowUseForTemplate	form	boolean	no	Allow use of this banner as a template
always2ndPrice	form	boolean	no	Always use second-price auction for this banner
applicationAdCategory	form	string	no	Application ad category. Allowed values: BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO Values: BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO.
applicationOperatingSystem	form	string	no	Target operating system for application banners. Allowed values: ANDROID, IOS Values: IOS, ANDROID.
applicationPreCheckPackages	form	string	no	App banner: packages to check on the device before showing the banner, comma-separated. Needs the Application Pre-Check permission
bannerType	form	string	conditional	Conditionally required — when creating a banner that is not built from a self-serve prototype (selfServeCampaignType). Creative type, which decides the fields that carry the creative: EXTERNAL_FILE - image hot-linked from imageBannerLink, click URL in url, size from adUnitId (or adUnitWidth + adUnitHeight); CODE - HTML/JS in code; VAST_2_0_TAG_URL - third-party VAST/VPAID tag in vastTagUrl (placementType VIDEO_PLACEMENT, size optional); EXTERNAL_VIDEO - video file URL in videoFileLink, click URL in url; TEMPLATE - templateId plus one request parameter per template property, named by the property key (see GET /rest-api/template/{id}/properties.do), an HTML5 ZIP property filled by html5ZipUrl and a FILE property by fileUrl; EXTERNAL_NATIVE - iconUrl / imageUrl / videoUrl (hot-linked) with title, description, callToAction and clickUrl; OPENRTB_DSP - dspPartnerId; LOCAL_FILE - the image stored on the ad server, uploaded as imageFile or fetched from imageFileUrl, click URL in url, size from adUnitId; LOCAL_VIDEO - the video stored on the ad server, uploaded as videoFile or fetched from videoFileUrl; LOCAL_NATIVE - icon / image / video stored on the ad server, uploaded as nativeIconFile / nativeImageFile / nativeVideoFile or fetched from nativeIconFileUrl / nativeImageFileUrl / nativeVideoFileUrl, with title, description, callToAction and clickUrl. Values: LOCAL_VIDEO, EXTERNAL_VIDEO, VAST_2_0_TAG_URL, VPAID_FRAMEWORK, ADVANCED_LOCAL_VIDEOS, LOCAL_FILE, EXTERNAL_FILE, CODE, TEMPLATE, OPENRTB_DSP, LOCAL_NATIVE, EXTERNAL_NATIVE.
boundedInstallActionId	form	integer	no	Mobile / app banner: id of the conversion action tracking the app install
callToAction	form	string	no	Call-to-action text for native banners
clickUrl	form	string	no	Click URL for native banners
code	form	string	no	HTML/JavaScript markup of a CODE banner
customParameters	form	array<object>	no	Custom native banner parameters
description	form	string	no	Description text for native banners
directFileDownload	form	boolean	no	Whether to enable direct file download for the banner
displayType	form	string	no	Android interstitial app banner: show it as a VIEW or as an ACTIVITY Values: VIEW, ACTIVITY.
dspPartnerId	form	integer	no	DSP partner ID for OpenRTB banners
enablePassbackFunctionality	form	boolean	no	Enable passback functionality for this banner
enableViewTracking	form	boolean	no	Whether to enable view tracking for this banner. Needs the Banner View Tracking permission
hardLinkage	form	boolean	no	Hard linkage: when true the banner serves only on the placements it is linked to. Needs the Link Placements to Banners permission
hostExternalFiles	form	boolean	no	EXTERNAL_FILE, EXTERNAL_VIDEO and EXTERNAL_NATIVE only: download the files from imageBannerLink / videoFileLink / iconUrl, imageUrl, videoUrl and serve our stored copy instead of the links. The links are kept; a changed link is downloaded again; false serves the links again and drops the copy. Omitted keeps the current setting.
iconHeight	form	integer	no	Native icon height in pixels
iconUrl	form	string	no	External URL to native icon image; an empty value removes it, omitted keeps it
iconWidth	form	integer	no	Native icon width in pixels
imageBannerLink	form	string	no	Image URL of an EXTERNAL_FILE banner. The image is hot-linked from this address at serve time unless hostExternalFiles is on; it should match the ad unit’s size.
imageFileUrl	form	string	no	URL of the image of a LOCAL_FILE banner - the multipart-free way to upload imageFile: the image is downloaded and stored as the banner’s own file (served from the ad server/CDN, not hot-linked; for a hot-linked image use EXTERNAL_FILE with imageBannerLink). GIF, JPEG, PNG or SVG (sanitised); the console’s size limit for the ad unit applies. On update it replaces the stored image. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
imageHeight	form	integer	no	Native image height in pixels
imageUrl	form	string	no	External URL to native image; an empty value removes it, omitted keeps it
imageWidth	form	integer	no	Native image width in pixels
inStreamVideoType	form	string	no	In-stream video ad type. Allowed values: LINEAR_VIDEO_AD (linear video), NON_LINEAR_VIDEO_AD (overlay) Values: LINEAR_VIDEO_AD, NON_LINEAR_VIDEO_AD.
labelUpdateType	form	string	no	How to update labels. Allowed values: add (append), overwrite (replace all existing), remove (delete specified), clear (remove all) Values: ADD, OVERWRITE, REMOVE, CLEAR.
labels	form	array<string>	no	Labels to apply to the banner
mimeTypes	form	string	no	OPENRTB_DSP banner on a video placement: video MIME types sent in the bid request, comma-separated. Needs the Open RTB permission
name	form	string	no	Banner name, up to 512 characters and never blank
nativeIconFileUrl	form	string	no	URL of the icon of a LOCAL_NATIVE banner - the multipart-free way to upload nativeIconFile. GIF, JPEG, PNG or SVG; fitted to iconWidth x iconHeight as an upload is. On update it replaces the stored icon. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
nativeImageFileUrl	form	string	no	URL of the main image of a LOCAL_NATIVE banner - the multipart-free way to upload nativeImageFile. GIF, JPEG, PNG or SVG; fitted to imageWidth x imageHeight as an upload is. On update it replaces the stored image. If its file name is already taken by the icon it is stored as image-<name>. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
nativeVideoFileUrl	form	string	no	URL of the video of a LOCAL_NATIVE banner - the multipart-free way to upload nativeVideoFile. MP4, at least videoWidth x videoHeight in the same orientation, up to the video size limit. On update it replaces the stored video. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
rating	form	number	no	Rating value for native banners (e.g., app store rating)
returnAsIframe	form	boolean	no	Video-placement banner: return the creative inside an iframe in the VAST response
skipButtonShowAfterSeconds	form	integer	no	Video banner: seconds before the player shows the skip button. Needs the Video Skip Button permission
subtitle	form	string	no	Subtitle text for native banners
target	form	string	no	HTML link target for the banner’s click-through URL (not applicable to CODE type) Values: _BLANK, _PARENT, _SELF, _TOP.
targetTemplateName	form	string	no	Target template name for template-based banners, up to 50 characters
thirdTrackingCode	form	object	no	Third-party tracking code (HTML/JavaScript fired with the impression) per country: thirdTrackingCode[*] for every country, thirdTrackingCode[US] for one - the key is * or a two-letter country code (any case; stored upper-case, GB as UK); any other key is not applied and is listed in ignoredFields. An empty value removes that code. Not applied to EXTERNAL_VIDEO banners. Needs the BANNER_THIRD_PARTY_TRACKING permission.
title	form	string	no	Title text for native banners
universalAdIdRegistry	form	string	no	Registry of the video creative’s Universal Ad ID (VAST UniversalAdId idRegistry); empty with a code set means ad-id.org
universalAdIdValue	form	string	no	ISCI / Ad-ID code of the video creative, sent as the VAST UniversalAdId; an empty string clears it
url	form	string	no	Click-through (landing page) URL of EXTERNAL_FILE, LOCAL_FILE, EXTERNAL_VIDEO, LOCAL_VIDEO and TEMPLATE banners. For a VAST_2_0_TAG_URL banner this field stores the VAST tag URL; send it as vastTagUrl instead.
usePlacementSize	form	boolean	no	Use placement size instead of banner size
vast40WrapperAllowMultipleAds	form	boolean	no	VAST 4.0: allow multiple ads in response
vast40WrapperFallbackOnNoAds	form	boolean	no	VAST 4.0: fallback when no ads available
vast40WrapperFollowAdditionalWrappers	form	boolean	no	VAST 4.0: follow additional wrapper redirects
vastTagUrl	form	string	no	Third-party VAST/VPAID tag URL of a VAST_2_0_TAG_URL banner (placementType VIDEO_PLACEMENT). Takes precedence over url, which older clients send for the same value. The player follows the tag, so the banner needs no ad unit; adUnitWidth + adUnitHeight are kept when given.
videoFileLink	form	string	no	Video file URL of an EXTERNAL_VIDEO banner
videoFileName	form	string	no	Video file name
videoFileUrl	form	string	no	URL of the video of a LOCAL_VIDEO banner - the multipart-free way to upload videoFile: the video (MP4 or FLV) is downloaded and stored as the banner’s own file, up to the configured video size limit (20 MB by default, never more than 100 MB). On update it replaces the stored video. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.
videoHeight	form	integer	no	Native video height in pixels
videoUrl	form	string	no	External URL to native video; an empty value removes it, omitted keeps it
videoWidth	form	integer	no	Native video width in pixels
weight	form	integer	no	Banner weight for rotation (higher weight = more impressions), 1 to 32767
placementType	form	string	conditional	Conditionally required — unless the banner is built from a self-serve prototype (selfServeCampaignType). Placement type of the ad: SITE_PLACEMENT, NON_STANDARD_SITE_PLACEMENT, MOBILE_SITE_PLACEMENT, VIDEO_PLACEMENT, APPLICATION_PLACEMENT, EMAIL_PLACEMENT or NATIVE_PLACEMENT. There is no click-through banner: a CLICK_THROUGH_PLACEMENT accepts a banner of any type, so create one of these and link it. Values: SITE_PLACEMENT, NON_STANDARD_SITE_PLACEMENT, MOBILE_SITE_PLACEMENT, VIDEO_PLACEMENT, APPLICATION_PLACEMENT, EMAIL_PLACEMENT, CLICK_THROUGH_PLACEMENT, NATIVE_PLACEMENT.
templateId	form	integer	conditional	Conditionally required — when bannerType is TEMPLATE. Template ID
vpaidFrameworkId	form	integer	conditional	Conditionally required — when bannerType is VPAID_FRAMEWORK. VPAID framework ID
selfServeCampaignType	form	string	no	Self-Serve campaign type; if set, banner is created from a prototype. Accepts enum name or integer ID for backward compatibility Values: BANNER_DESKTOP, BANNER_MOBILE, BANNER_APPLICATION, BANNER_NATIVE, POP_UNDER, INTERSTITIAL_MOBILE, INTERSTITIAL_APPLICATION.
linkToPlacements	form	boolean	no	If true, after creation link the banner to every placement its auto-linking rules match: the banner’s own when allowNewPlacementsAutoLinking is on (narrowed by autolinkCategories / autoLinkLabels), otherwise its campaign’s. With auto-linking off on both, or without the Link Placements to Banners or Auto-Linking Settings permission, nothing is linked and the field is listed in ignoredFields with the reason.
status	form	string	no	Initial approval status (NEW, PENDING, APPROVED, REJECTED). A status other than the one the banner is created with needs the BANNERS_APPROVAL permission; without it the field is listed in ignoredFields and the banner is created with its default status. Values: NEW, PENDING, APPROVED, REJECTED.
mediaAssetId	form	integer	no	Media library file the creative uses instead of an upload (GET /rest-api/media-library/assets.do): a video for LOCAL_VIDEO, an image for LOCAL_FILE, a video ADVANCED_LOCAL_VIDEOS adds to its media files. The file is referenced, not copied. A TEMPLATE banner whose template has one HTML5 ZIP property takes a library ZIP here; with several, send mediaAsset.<property key> per property, e.g. mediaAsset.$$HTML5_HEAD$$=42. Requires the MEDIA_LIBRARY permission.
html5ZipUrl	form	string	no	URL of the HTML5 creative’s ZIP archive, for a TEMPLATE banner whose template has one HTML5 ZIP property - the way to supply it without a multipart upload. At most 10 MB; the archive must unpack within the HTML5 limits (by default 1000 files, 20 MB a file, 50 MB in all, no path outside its folder). The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. For a template with several HTML5 ZIP properties send html5ZipUrl[<property key>] per property instead, e.g. html5ZipUrl[$$HTML5_HEAD$$]. On update it replaces the stored archive.
fileUrl	form	string	no	URL of the file for a TEMPLATE banner’s FILE property (an image or video the template renders) - the way to supply it without a multipart upload; the file must be of a content type the property allows. At most the video size limit (10 MB when that is lower). The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. For a template with several FILE properties send fileUrl[<property key>] per property instead, e.g. fileUrl[$$IMAGE$$]. On update it replaces the stored file.

Request body (multipart/form-data): form with fields imageFile, nativeIconFile, nativeImageFile, nativeVideoFile, videoFile.

Responses: 200 — Banner created successfully. Errors follow the shared conventions.

GET /rest-api/banner/dspPartners.do

Request examples

Get DSP partners.

No parameters beyond authentication.

Responses: 200 — List of DSP partners. Errors follow the shared conventions.

GET /rest-api/banner/placement/{placementId}/banners.do

Request examples

Get banners linked to placement.

Parameter	In	Type	Required	Description
placementId	path	integer	yes	ID of the placement to list linked banners for

Responses: 200 — List of linked banners · 404 — Placement not found. Errors follow the shared conventions.

GET /rest-api/banners.do

Request examples

List banners.

Parameter	In	Type	Required	Description
advertisingCategories	query	array<integer>	no	IDs of advertising categories to filter by
templateIds	query	array<integer>	no	Template IDs to filter by
approvalStatuses	query	array<string>	no	Approval statuses to filter by (e.g., NEW, PENDING, APPROVED, REJECTED) Values: NEW, PENDING, APPROVED, REJECTED.
labels	query	array<string>	no	Label names to filter by
campaignId	query	integer	no	Campaign ID to restrict results to a single campaign
offset	query	integer	no	Pagination offset (0-based)
limit	query	integer	no	Maximum number of banners to return
selfServRequest	query	boolean	no	If true, returns the Self-Serve response format
bannerName	query	string	no	Part of the banner name to search for, case-insensitive
active	query	boolean	no	When set, returns only active (true) or only inactive (false) banners; omit to return both
placementTypes	query	array<string>	no	Placement types the banners are made for, e.g. VIDEO_PLACEMENT; a banner matching any of them is returned Values: SITE_PLACEMENT, NON_STANDARD_SITE_PLACEMENT, MOBILE_SITE_PLACEMENT, VIDEO_PLACEMENT, APPLICATION_PLACEMENT, EMAIL_PLACEMENT, CLICK_THROUGH_PLACEMENT, NATIVE_PLACEMENT.
bannerTypes	query	array<string>	no	Creative types to filter by, e.g. VAST_2_0_TAG_URL; a banner matching any of them is returned Values: LOCAL_VIDEO, EXTERNAL_VIDEO, VAST_2_0_TAG_URL, VPAID_FRAMEWORK, ADVANCED_LOCAL_VIDEOS, LOCAL_FILE, EXTERNAL_FILE, CODE, TEMPLATE, OPENRTB_DSP, LOCAL_NATIVE, EXTERNAL_NATIVE.
fields	query	array<string>	no	Return only these fields of each entity, comma-separated; id is always kept. A requested field no returned row carries is named in the X-Ignored-Fields response header
filter	query	object	no	Keep only entities matching every key, e.g. filter[cpaOptimization]=true&filter[hasLimit]=true. Keys are the entity’s on/off settings (active, enableTargeting, cpaOptimization, alwaysRedirect, …) and a has<Relation> flag for each setting kept in rows of its own (hasLimit, hasPricing, hasFrequencyCapping, hasTrackingCode, hasPriceAdjustmentRules, hasLabels, hasBanners, …), true when the relation holds a row; hasCapping, hasLimits and hasTargetingRules group the relations of their kind. An unknown key is a 400 that lists every valid key for the list.

Responses: 200 — List of banners. Errors follow the shared conventions.

GET /rest-api/banners/{bannerId}/placements.do

Request examples

Get banner placements.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	Unique identifier of the banner whose linked placements should be retrieved

Responses: 200 — List of linked placements · 404 — The banner does not exist or is deleted. Errors follow the shared conventions.

PUT /rest-api/banners/{bannerId}/placements.do

Request examples

Update banner placements.

Parameter	In	Type	Required	Description
ids	form	array<integer>	yes	Array of placement IDs to link to the banner. An id of no placement or of a deleted one is skipped and listed in ‘skipped’ with the reason; every other placement must be compatible with the banner type
bannerId	path	integer	yes	Unique identifier of the banner to update placement links for
append	form	boolean	no	When true, the provided placement IDs are added to the existing linked placements. When false (default), the provided IDs replace all existing links

Responses: 200 — Operation result with success status · 404 — Not found — resource does not exist. Errors follow the shared conventions.

DELETE /rest-api/banners/{bannerId}/placements.do

Request examples

Remove banner placements.

Parameter	In	Type	Required	Description
bannerId	path	integer	yes	Unique identifier of the banner to remove placement links from
removeIds	form	array<integer>	no	Array of placement IDs to unlink from the banner. All IDs must currently be linked to the banner

Responses: 200 — Operation result with success status · 404 — Not found — resource does not exist. Errors follow the shared conventions.

GET /rest-api/banners/{bannerType}/adunit/values.do

Request examples

Get ad unit values by banner type.

Parameter	In	Type	Required	Description
bannerType	path	string	yes	Banner type enum value (e.g. LOCAL_FILE, CODE, LOCAL_VIDEO, OPENRTB_DSP) Values: LOCAL_VIDEO, EXTERNAL_VIDEO, VAST_2_0_TAG_URL, VPAID_FRAMEWORK, ADVANCED_LOCAL_VIDEOS, LOCAL_FILE, EXTERNAL_FILE, CODE, TEMPLATE, OPENRTB_DSP, LOCAL_NATIVE, EXTERNAL_NATIVE.

Responses: 200 — List of ad unit values · 404 — No matching ad units found. Errors follow the shared conventions.

POST /rest-api/banners/labels.do

Request examples

Change labels of many banners.

Parameter	In	Type	Required	Description
ids	form	array<integer>	yes	Banner IDs to change, 1 to 500
labels	form	array<string>	no	Label names, comma-separated or repeated
labelUpdateType	form	string	no	ADD (default), OVERWRITE, REMOVE or CLEAR Values: ADD, OVERWRITE, REMOVE, CLEAR.

Responses: 200 — Batch applied · 404 — None of the ids names an existing banner. Errors follow the shared conventions.

POST /rest-api/banners/reaprove.do

Request examples

Reapprove banners.

Parameter	In	Type	Required	Description
bannerIds	form	array<integer>	yes	IDs of banners to reset for re-approval

Responses: 200 — The ids whose status changed. Errors follow the shared conventions.

POST /rest-api/banners/sendToApprove.do

Request examples

Send banners to approval.

Parameter	In	Type	Required	Description
bannerIds	form	array<integer>	yes	IDs of banners to submit for approval

Responses: 200 — The ids whose status changed. Errors follow the shared conventions.

POST /rest-api/banners/status.do

Request examples

Switch banners on or off.

Parameter	In	Type	Required	Description
ids	form	array<integer>	yes	Banner IDs to switch, 1 to 500
active	form	boolean	yes	true to switch the banners on, false to switch them off

Responses: 200 — Batch applied · 404 — None of the ids names an existing banner. Errors follow the shared conventions.

GET /rest-api/banners/urls.do

Request examples

Get banner landing URLs.

Parameter	In	Type	Required	Description
advertisingCategories	query	array<integer>	no	IDs of advertising categories to filter results by
bannerIds	query	array<integer>	no	IDs of specific banners to retrieve URLs for

Responses: 200 — List of banner URLs. Errors follow the shared conventions.

POST /rest-api/banners/urls.do

Request examples

Update banner landing URLs in batch.

Request body (application/json, required): JSON array; each element a JSON object with fields id, url.

Responses: 200 — Every banner was saved, or some were: success=false with ‘failures’ when not all of them. Errors follow the shared conventions.

GET /rest-api/categories/advertising.do

Request examples

Get advertising categories.

No parameters beyond authentication.

Responses: 200 — List of advertising categories. Errors follow the shared conventions.

GET /rest-api/categories/publishing.do

Request examples

Get publishing categories.

No parameters beyond authentication.

Responses: 200 — List of publishing categories. Errors follow the shared conventions.

GET /rest-api/prototype/{prototypeId}.do

Request examples

Get banner prototype by ID.

Parameter	In	Type	Required	Description
prototypeId	path	integer	yes	Unique numeric identifier of the banner prototype to retrieve

Responses: 200 — JSON object containing the banner prototype with id, type, banner details, and defaultAction · 404 — Not found — resource does not exist · 500 — Internal server error while retrieving the prototype. Errors follow the shared conventions.

GET /rest-api/prototype/banner/{prototypeType}.do

Request examples

Get banner prototype by campaign type.

Parameter	In	Type	Required	Description
prototypeType	path	string	yes	Self-serve campaign type enum value (e.g. BANNER_DESKTOP, BANNER_MOBILE, VIDEO_DESKTOP, VIDEO_MOBILE) Values: BANNER_DESKTOP, BANNER_MOBILE, BANNER_APPLICATION, BANNER_NATIVE, POP_UNDER, INTERSTITIAL_MOBILE, INTERSTITIAL_APPLICATION.

Responses: 200 — JSON object containing the banner prototype with id, type, banner details, and defaultAction · 404 — Not found — resource does not exist · 500 — Internal server error while retrieving the prototype. Errors follow the shared conventions.

GET /rest-api/prototype/banner/action.do

Request examples

Get prototype actions by banner IDs.

Parameter	In	Type	Required	Description
bannerIds	query	array<integer>	yes	Comma-separated set of unique numeric banner IDs to look up prototype actions for (e.g. bannerIds=838,839,840)

Responses: 200 — JSON array of action objects, each containing id, actionTrackUrl, pixelTracking, securePixelTracking, subIdActionTrackUrl, and code · 500 — Internal server error while retrieving prototype actions. Errors follow the shared conventions.

GET /rest-api/prototype/list.do

Request examples

List banner prototypes.

No parameters beyond authentication.

Responses: 200 — JSON array of banner prototype objects, each containing id, type, banner details, and defaultAction. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/add.do

Request examples

Add banner tracking code.

Parameter	In	Type	Required	Description
domainId	form	integer	yes	The unique numeric identifier of the banner to add the tracking code to
country	form	string	yes	ISO country code to target (e.g., ‘US’, ‘GB’), or ’*’ to set a global tracking code that applies to all countries
code	form	string	yes	The HTML tracking code snippet to be injected during ad serving for the specified country

Responses: 200 — Operation result with success status. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/add/batch.do

Request examples

Batch add banner tracking codes.

Parameter	In	Type	Required	Description
domainIds	form	array<integer>	yes	Array of unique numeric banner identifiers to add the tracking code to
country	form	string	yes	ISO country code to target (e.g., ‘US’, ‘GB’), or ’*’ to set a global tracking code that applies to all countries
code	form	string	yes	The HTML tracking code snippet to be injected during ad serving for each banner and the specified country

Responses: 200 — Map of banner IDs to operation results. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/delete.do

Request examples

Delete banner tracking codes.

Parameter	In	Type	Required	Description
domainId	form	integer	yes	The unique numeric identifier of the banner to delete tracking codes from
countryTrackingCodeIds	form	array<integer>	no	Array of tracking code record IDs to delete. Can be omitted if only clearing the global code
clearGlobalTrackingCode	form	boolean	no	When true, clears the global (country=’*’) tracking code for this banner. Can be combined with countryTrackingCodeIds

Responses: 200 — Operation result with success status. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/disable-tracking-code.do

Request examples

Disable banner tracking code.

Parameter	In	Type	Required	Description
id	form	integer	yes	The unique numeric identifier of the banner to disable tracking codes for

Responses: 200 — Operation result with success status · 404 — No such banner. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/edit.do

Request examples

Edit banner tracking code.

Parameter	In	Type	Required	Description
id	form	integer	yes	The unique numeric identifier of the existing tracking code record to update
domainId	form	integer	yes	The unique numeric identifier of the banner that owns this tracking code
country	form	string	yes	ISO country code to target (e.g., ‘US’, ‘GB’), or ’*’ for a global tracking code
code	form	string	yes	The updated HTML tracking code snippet to be injected during ad serving

Responses: 200 — Operation result with success status · 404 — No such banner, or no such tracking code of it. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/enable-tracking-code.do

Request examples

Enable banner tracking code.

Parameter	In	Type	Required	Description
id	form	integer	yes	The unique numeric identifier of the banner to enable tracking codes for

Responses: 200 — Operation result with success status · 404 — No such banner. Errors follow the shared conventions.

POST /rest-api/tracking-code/banner/global-clear/batch.do

Request examples

Batch clear banner global tracking codes.

Parameter	In	Type	Required	Description
domainIds	form	array<integer>	yes	Array of unique numeric banner identifiers to clear global tracking codes from

Responses: 200 — Map of banner IDs to operation results. Errors follow the shared conventions.

GET /rest-api/tracking-code/banner/list.do

Request examples

List banner tracking codes.

Parameter	In	Type	Required	Description
domainId	query	integer	yes	The unique numeric identifier of the banner to list tracking codes for

Responses: 200 — List of banner country tracking codes. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/add.do

Request examples

Add placement tracking code.

Parameter	In	Type	Required	Description
domainId	form	integer	yes	The unique numeric identifier of the placement to add the tracking code to
country	form	string	yes	ISO country code to target (e.g., ‘US’, ‘GB’), or ’*’ to set a global tracking code that applies to all countries
code	form	string	yes	The HTML tracking code snippet to be injected during ad serving for the specified country

Responses: 200 — Operation result with success status. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/add/batch.do

Request examples

Batch add placement tracking codes.

Parameter	In	Type	Required	Description
domainIds	form	array<integer>	yes	Array of unique numeric placement identifiers to add the tracking code to
country	form	string	yes	ISO country code to target (e.g., ‘US’, ‘GB’), or ’*’ to set a global tracking code that applies to all countries
code	form	string	yes	The HTML tracking code snippet to be injected during ad serving for each placement and the specified country

Responses: 200 — Map of placement IDs to operation results. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/delete.do

Request examples

Delete placement tracking codes.

Parameter	In	Type	Required	Description
domainId	form	integer	yes	The unique numeric identifier of the placement to delete tracking codes from
countryTrackingCodeIds	form	array<integer>	no	Array of tracking code record IDs to delete. Can be omitted if only clearing the global code
clearGlobalTrackingCode	form	boolean	no	When true, clears the global (country=’*’) tracking code for this placement. Can be combined with countryTrackingCodeIds

Responses: 200 — Operation result with success status. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/disable-tracking-code.do

Request examples

Disable placement tracking code.

Parameter	In	Type	Required	Description
id	form	integer	yes	The unique numeric identifier of the placement to disable tracking codes for

Responses: 200 — Operation result with success status · 404 — No such placement. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/edit.do

Request examples

Edit placement tracking code.

Parameter	In	Type	Required	Description
id	form	integer	yes	The unique numeric identifier of the existing tracking code record to update
domainId	form	integer	yes	The unique numeric identifier of the placement that owns this tracking code
country	form	string	yes	ISO country code to target (e.g., ‘US’, ‘GB’), or ’*’ for a global tracking code
code	form	string	yes	The updated HTML tracking code snippet to be injected during ad serving

Responses: 200 — Operation result with success status · 404 — No such placement, or no such tracking code of it. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/enable-tracking-code.do

Request examples

Enable placement tracking code.

Parameter	In	Type	Required	Description
id	form	integer	yes	The unique numeric identifier of the placement to enable tracking codes for

Responses: 200 — Operation result with success status · 404 — No such placement. Errors follow the shared conventions.

POST /rest-api/tracking-code/placement/global-clear/batch.do

Request examples

Batch clear placement global tracking codes.

Parameter	In	Type	Required	Description
domainIds	form	array<integer>	yes	Array of unique numeric placement identifiers to clear global tracking codes from

Responses: 200 — Map of placement IDs to operation results. Errors follow the shared conventions.

GET /rest-api/tracking-code/placement/list.do

Request examples

List placement tracking codes.

Parameter	In	Type	Required	Description
domainId	query	integer	yes	The unique numeric identifier of the placement to list tracking codes for

Responses: 200 — List of placement country tracking codes. Errors follow the shared conventions.

GET /rest-api/url-check.do

Request examples

Check what a URL returns.

Parameter	In	Type	Required	Description
url	query	string	yes	The URL to request, http or https
as	query	string	no	The device the request poses as: desktop (default), iphone or android
mode	query	string	no	auto (default: VAST or page by the body), head (status and headers only), vast or page

Responses: 200 — {success, url, device, userAgent, status, finalHost, redirects:[{status, from, location, ms}], contentType, contentLength, bytesRead, truncated, ms, error:{code, message}, readAs, vast:{version, ads, noAd, ad:[..]}, noAdExplanation, wrapperChain:[{depth, host, status, vast}], page:{title, candidates:[{selector, tag, why, matches}], playerScripts, note}}; error.code is one of FORBIDDEN_REDIRECT, TOO_MANY_REDIRECTS, BAD_REDIRECT, TIMEOUT, UNKNOWN_HOST, UNREACHABLE · 429 — More than 30 checks in the last minute. Errors follow the shared conventions.

Related

• REST API overview — authentication and conventions
• API endpoint reference by tag
• Entities — create, read, update, delete via API